Alias

SignatureWithDeviceForDocumentCreation

Description

Creates an asynchronous process for generating a digital signature on a document from its hash with a mobile device.

The obtaining of the result of the process (the signature, if the process is successful), is performed with the Obtain the result of a signature process operation.

The signature can be created with any of the signing identities selected (using an identifier or labels) by the selectors included in the request. All these identities belong to the user on behalf of whom the operation is performed.

Request

POST /trustedx-resources/esigp/v1/signatures/device/commitment/document

Content-Type Header

Content-Type: application/json

Body

The body of the request contains the following JSON object:

{
    "input" : {
        "service" : {
            "id" : {string},
            "name" : {string},
            "domain" : {string}
        },
        "digest_url" : {string},
        "digest_value" : {string},
        "digest_algorithm" : {string},
        "document_url" : {string},
        "document_alias" : {string},
        "root_certs" : [ {string} ],
        "document_info" : {
            "html" : {string}
        }
     },
    "sign_identities" : [{"id" : {string}} | "labels" : [{string}] ],
    "notify" : {boolean}
}

Property	Usage	Description
`input`	Required	Information on the document to be signed.
`input.service`	Optional	Client application requesting the creation of a signature.
`input.service.id`	Optional	Identifier of the client application.
`input.service.name`	Optional	Name of the client application.
`input.service.domain`	Optional	Domain of the client application.
`input.digest_url`	Optional	URL for obtaining the hash to be signed encoded in base64 and the hash algorithm used. This property is required when `digest_value` is omitted.
`input.digest_value`	Optional	Hash of the document to be signed encoded in base64. This property is required when `digest_url` is omitted.
`input.digest_algorithm`	Optional	Algorithm used to calculate the hash of the document (sha1, sha256, sha384 and sha512). This property is required when `digest_url` is omitted.
`input.document_url`	Required	URL of the document to be signed.
`input.document_alias`	Required	Alias of the document to be signed.
`input.root_certs`	Optional	Certificates encoded in base64 of the certification paths of the `input.digest_url` and `input.document_url` TLS servers. If this optional field is omitted, the path of the electronic signature provider's TLS server is trusted.
`input.document_info`	Optional	Additional information on the document to be signed.
`input.document_info.html`	Optional	HTML encoded in base64 with the information displayed to the user on the document to be signed.
`sign_identities[]`	Required	Signing identity selectors with which the signature can be created.
`sign_identities[].id`	Optional	Identifier that the signing identity must have according to a selector (if the selector only allows using one signing identity). If this information is present, the selector cannot contain `labels[]`.
`sign_identities[].labels[]`	Optional	Labels that the signing identity must have according to a selector (if the selector allows using multiple signing identities). If this information is present, the selector cannot contain id.
`notify`	Required	Indication whether a push notification must be sent to the mobile device to notify it that it has a pending signature operation.

Lastly, the signature is created using one (any) of the signing identities allowed by the selectors.

A selector of the signing identities can select more than one signing identity. For instance, if the user has a signing identity with the labels [RecognizeSignature and SimplePolicy] in their mobile and a signing identity with the label [RecognizeSignature] in their tablet, the following selector (represented in JSON) would allow creating the document signature both with the user's mobile and tablet.

"sign_identities" : [{"labels" : ["QualifiedSignature"]}]

Authorization

The request must contain a bearer access token generated by a trusted authorization server of the service requested to create the signature process and that is associated to the domain of the signing identity to be used for generating the signature. This token must have a scope that includes the urn:safelayer:eidas:sign:identity:use:device value and must be used as explained in RFC 6750. Basically, the token must be included in an HTTP Authorization header as follows:

Authorization: Bearer <token>

The access token must be obtained via an authorization code grant OAuth 2.0 flow.

Response

Status-Line

If the document's signature process is created successfully, the HTTP response will contain the following Status-Line (see HTTP Response Status for all the possible cases).

HTTP/1.1 201 Created

Location Header

URL of the signature process resource created.

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

Contains a JSON object with the following structure:

{
    "signature" : {Signature},
    "wakeup_device_uri" : {string}
}

Property

Description

signature

JSON representation of the document signature process resource created.

wakeup_device_uri

URL for starting the signature application (mobile ID) in the mobile device. This property is only returned if:

The signature application can be started from a URL.
The notify parameter takes the false value.